Skip to main content
POST
/
api
/
call
/
add-phone
curl --location '{{baseUrl}}/api/call/add-phone' \
  --header 'Authorization: Bearer {{authToken}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "userId": "64e5f12345abcdef12345678",
    "phoneNumber": "12125551234",
    "integration": "twilio",
    "authToken": "your_auth_token",
    "accSId": "your_account_sid"
  }'

{
  "message": "Phone number added successfully",
  "status": true,
  "code": 201,
  "errorMessage": "",
  "data": {
    "_id": "64e5f12345abcdef87654321",
    "userId": "64e5f12345abcdef12345678",
    "phoneNumber": "12125551234",
    "integration": "twilio",
    "createdAt": "2025-05-15T10:30:00.000Z"
  }
}

​
Overview

Add a phone number to your workspace that can be used for outbound calling campaigns or inbound call handling. The system supports multiple integrations including Plivo, Twilio, and Telnyx. Credentials are validated before the number is saved, and webhooks are automatically configured for the selected integration.

​
Prerequisites

  • Bearer token for authenticated workspace access
  • Valid phone number credentials for your chosen integration provider
  • Phone number must be owned by your integration account

​
Request

​
Authorization
string
required
Bearer token for the authenticated workspace account.
​
userId
string
required
ID of the user who will own this phone number.
​
phoneNumber
string
required
Phone number with country code (e.g., “12125551234”). The + prefix is optional. Must be owned by your integration account.
​
integration
string
required
Integration provider for this phone number. Choose one of: plivo, twilio, or telnyx.
​
authToken
string
required
Authentication token for your integration provider account. For Plivo, this is the Auth Token. For Twilio, this is the Auth Token. For Telnyx, this is the API Key.
​
accSId
string
required
Account identifier for your integration provider. For Plivo, this is the Auth ID. For Twilio, this is the Account SID. For Telnyx, this is the App ID (automatically configured).
curl --location '{{baseUrl}}/api/call/add-phone' \
  --header 'Authorization: Bearer {{authToken}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "userId": "64e5f12345abcdef12345678",
    "phoneNumber": "12125551234",
    "integration": "twilio",
    "authToken": "your_auth_token",
    "accSId": "your_account_sid"
  }'

​
Response

{
  "message": "Phone number added successfully",
  "status": true,
  "code": 201,
  "errorMessage": "",
  "data": {
    "_id": "64e5f12345abcdef87654321",
    "userId": "64e5f12345abcdef12345678",
    "phoneNumber": "12125551234",
    "integration": "twilio",
    "createdAt": "2025-05-15T10:30:00.000Z"
  }
}
​
data
object
required
Phone number record that was created.
​
data._id
string
required
Unique identifier for the phone number record.
​
data.phoneNumber
string
required
Phone number that was added (with country code).
​
data.integration
string
required
Integration provider used for this number.

​
Error Handling

  • 400 Bad Request – Invalid User ID format, phone number already exists for this user, or invalid credentials for the integration provider.
  • 404 Not Found – User not found with the provided userId.
  • 500 Internal Server Error – Failed to set up integration webhooks or other server errors.
Integration-Specific Behavior:
  • Plivo: Validates Auth ID and Auth Token, then creates or reuses a Plivo application for webhook configuration.
  • Twilio: Validates Account SID, Auth Token, and phone number ownership, then configures webhooks for the number.
  • Telnyx: Validates API Key and phone number, then automatically configures webhooks.
All integrations automatically set up webhook endpoints to receive call status updates and recordings.
Phone numbers must be unique per user. If you attempt to add a number that already exists for the user, the request will fail with a 400 error.

Authorizations

​
Authorization
string
header
required

Bearer token authentication for workspace access

Body

application/json
​
userId
string
required
Example:

"64e5f12345abcdef12345678"

​
phoneNumber
string
required
Example:

"12125551234"

​
integration
enum<string>
required
Available options:
plivo,
twilio,
telnyx
Example:

"twilio"

​
authToken
string
required
Example:

"your_auth_token"

​
accSId
string
required
Example:

"your_account_sid"

Response

Phone number added successfully